home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / nss / secpkcs7.h < prev    next >
C/C++ Source or Header  |  2006-04-20  |  24KB  |  627 lines
  1. /* ***** BEGIN LICENSE BLOCK *****
  2.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  3.  *
  4.  * The contents of this file are subject to the Mozilla Public License Version
  5.  * 1.1 (the "License"); you may not use this file except in compliance with
  6.  * the License. You may obtain a copy of the License at
  7.  * http://www.mozilla.org/MPL/
  8.  *
  9.  * Software distributed under the License is distributed on an "AS IS" basis,
  10.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11.  * for the specific language governing rights and limitations under the
  12.  * License.
  13.  *
  14.  * The Original Code is the Netscape security libraries.
  15.  *
  16.  * The Initial Developer of the Original Code is
  17.  * Netscape Communications Corporation.
  18.  * Portions created by the Initial Developer are Copyright (C) 1994-2000
  19.  * the Initial Developer. All Rights Reserved.
  20.  *
  21.  * Contributor(s):
  22.  *
  23.  * Alternatively, the contents of this file may be used under the terms of
  24.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  25.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  26.  * in which case the provisions of the GPL or the LGPL are applicable instead
  27.  * of those above. If you wish to allow use of your version of this file only
  28.  * under the terms of either the GPL or the LGPL, and not to allow others to
  29.  * use your version of this file under the terms of the MPL, indicate your
  30.  * decision by deleting the provisions above and replace them with the notice
  31.  * and other provisions required by the GPL or the LGPL. If you do not delete
  32.  * the provisions above, a recipient may use your version of this file under
  33.  * the terms of any one of the MPL, the GPL or the LGPL.
  34.  *
  35.  * ***** END LICENSE BLOCK ***** */
  36.  
  37. /*
  38.  * Interface to the PKCS7 implementation.
  39.  *
  40.  * $Id: secpkcs7.h,v 1.5 2004/04/25 15:03:13 gerv%gerv.net Exp $
  41.  */
  42.  
  43. #ifndef _SECPKCS7_H_
  44. #define _SECPKCS7_H_
  45.  
  46. #include "seccomon.h"
  47.  
  48. #include "secoidt.h"
  49. #include "certt.h"
  50. #include "keyt.h"
  51. #include "hasht.h"
  52. #include "pkcs7t.h"
  53.  
  54. extern const SEC_ASN1Template sec_PKCS7ContentInfoTemplate[];
  55.  
  56. /************************************************************************/
  57. SEC_BEGIN_PROTOS
  58.  
  59. /************************************************************************
  60.  *    Miscellaneous
  61.  ************************************************************************/
  62.  
  63. /*
  64.  * Returns the content type of the given contentInfo.
  65.  */
  66. extern SECOidTag SEC_PKCS7ContentType (SEC_PKCS7ContentInfo *cinfo);
  67.  
  68. /*
  69.  * Destroy a PKCS7 contentInfo and all of its sub-pieces.
  70.  */
  71. extern void SEC_PKCS7DestroyContentInfo(SEC_PKCS7ContentInfo *contentInfo);
  72.  
  73. /*
  74.  * Copy a PKCS7 contentInfo.  A Destroy is needed on *each* copy.
  75.  */
  76. extern SEC_PKCS7ContentInfo *
  77. SEC_PKCS7CopyContentInfo(SEC_PKCS7ContentInfo *contentInfo);
  78.  
  79. /*
  80.  * Return a pointer to the actual content.  In the case of those types
  81.  * which are encrypted, this returns the *plain* content.
  82.  */
  83. extern SECItem *SEC_PKCS7GetContent(SEC_PKCS7ContentInfo *cinfo);
  84.  
  85. /************************************************************************
  86.  *    PKCS7 Decoding, Verification, etc..
  87.  ************************************************************************/
  88.  
  89. extern SEC_PKCS7DecoderContext *
  90. SEC_PKCS7DecoderStart(SEC_PKCS7DecoderContentCallback callback,
  91.               void *callback_arg,
  92.               SECKEYGetPasswordKey pwfn, void *pwfn_arg,
  93.               SEC_PKCS7GetDecryptKeyCallback decrypt_key_cb, 
  94.               void *decrypt_key_cb_arg,
  95.               SEC_PKCS7DecryptionAllowedCallback decrypt_allowed_cb);
  96.  
  97. extern SECStatus
  98. SEC_PKCS7DecoderUpdate(SEC_PKCS7DecoderContext *p7dcx,
  99.                const char *buf, unsigned long len);
  100.  
  101. extern SEC_PKCS7ContentInfo *
  102. SEC_PKCS7DecoderFinish(SEC_PKCS7DecoderContext *p7dcx);
  103.  
  104.  
  105. /*  Abort the underlying ASN.1 stream & set an error  */
  106. void SEC_PKCS7DecoderAbort(SEC_PKCS7DecoderContext *p7dcx, int error);
  107.  
  108. extern SEC_PKCS7ContentInfo *
  109. SEC_PKCS7DecodeItem(SECItem *p7item,
  110.             SEC_PKCS7DecoderContentCallback cb, void *cb_arg,
  111.             SECKEYGetPasswordKey pwfn, void *pwfn_arg,
  112.             SEC_PKCS7GetDecryptKeyCallback decrypt_key_cb, 
  113.             void *decrypt_key_cb_arg,
  114.             SEC_PKCS7DecryptionAllowedCallback decrypt_allowed_cb);
  115.  
  116. extern PRBool SEC_PKCS7ContainsCertsOrCrls(SEC_PKCS7ContentInfo *cinfo);
  117.  
  118. /* checks to see if the contents of the content info is
  119.  * empty.  it so, PR_TRUE is returned.  PR_FALSE, otherwise.
  120.  *
  121.  * minLen is used to specify a minimum size.  if content size <= minLen,
  122.  * content is assumed empty.
  123.  */
  124. extern PRBool 
  125. SEC_PKCS7IsContentEmpty(SEC_PKCS7ContentInfo *cinfo, unsigned int minLen); 
  126.  
  127. extern PRBool SEC_PKCS7ContentIsEncrypted(SEC_PKCS7ContentInfo *cinfo);
  128.  
  129. /*
  130.  * If the PKCS7 content has a signature (not just *could* have a signature)
  131.  * return true; false otherwise.  This can/should be called before calling
  132.  * VerifySignature, which will always indicate failure if no signature is
  133.  * present, but that does not mean there even was a signature!
  134.  * Note that the content itself can be empty (detached content was sent
  135.  * another way); it is the presence of the signature that matters.
  136.  */
  137. extern PRBool SEC_PKCS7ContentIsSigned(SEC_PKCS7ContentInfo *cinfo);
  138.  
  139. /*
  140.  * SEC_PKCS7VerifySignature
  141.  *    Look at a PKCS7 contentInfo and check if the signature is good.
  142.  *    The verification checks that the signing cert is valid and trusted
  143.  *    for the purpose specified by "certusage".
  144.  *
  145.  *    In addition, if "keepcerts" is true, add any new certificates found
  146.  *    into our local database.
  147.  */
  148. extern PRBool SEC_PKCS7VerifySignature(SEC_PKCS7ContentInfo *cinfo,
  149.                        SECCertUsage certusage,
  150.                        PRBool keepcerts);
  151.  
  152. /*
  153.  * SEC_PKCS7VerifyDetachedSignature
  154.  *    Look at a PKCS7 contentInfo and check if the signature matches
  155.  *    a passed-in digest (calculated, supposedly, from detached contents).
  156.  *    The verification checks that the signing cert is valid and trusted
  157.  *    for the purpose specified by "certusage".
  158.  *
  159.  *    In addition, if "keepcerts" is true, add any new certificates found
  160.  *    into our local database.
  161.  */
  162. extern PRBool SEC_PKCS7VerifyDetachedSignature(SEC_PKCS7ContentInfo *cinfo,
  163.                            SECCertUsage certusage,
  164.                            SECItem *detached_digest,
  165.                            HASH_HashType digest_type,
  166.                            PRBool keepcerts);
  167.  
  168. /*
  169.  * SEC_PKCS7GetSignerCommonName, SEC_PKCS7GetSignerEmailAddress
  170.  *      The passed-in contentInfo is espected to be Signed, and these
  171.  *      functions return the specified portion of the full signer name.
  172.  *
  173.  *      Returns a pointer to allocated memory, which must be freed.
  174.  *      A NULL return value is an error.
  175.  */
  176. extern char *SEC_PKCS7GetSignerCommonName(SEC_PKCS7ContentInfo *cinfo);
  177. extern char *SEC_PKCS7GetSignerEmailAddress(SEC_PKCS7ContentInfo *cinfo);
  178.  
  179. /*
  180.  * Return the the signing time, in UTCTime format, of a PKCS7 contentInfo.
  181.  */
  182. extern SECItem *SEC_PKCS7GetSigningTime(SEC_PKCS7ContentInfo *cinfo);
  183.  
  184.  
  185. /************************************************************************
  186.  *    PKCS7 Creation and Encoding.
  187.  ************************************************************************/
  188.  
  189. /*
  190.  * Start a PKCS7 signing context.
  191.  *
  192.  * "cert" is the cert that will be used to sign the data.  It will be
  193.  * checked for validity.
  194.  *
  195.  * "certusage" describes the signing usage (e.g. certUsageEmailSigner)
  196.  * XXX Maybe SECCertUsage should be split so that our caller just says
  197.  * "email" and *we* add the "signing" part -- otherwise our caller
  198.  * could be lying about the usage; we do not want to allow encryption
  199.  * certs for signing or vice versa.
  200.  *
  201.  * "certdb" is the cert database to use for verifying the cert.
  202.  * It can be NULL if a default database is available (like in the client).
  203.  * 
  204.  * "digestalg" names the digest algorithm (e.g. SEC_OID_SHA1).
  205.  *
  206.  * "digest" is the actual digest of the data.  It must be provided in
  207.  * the case of detached data or NULL if the content will be included.
  208.  *
  209.  * The return value can be passed to functions which add things to
  210.  * it like attributes, then eventually to SEC_PKCS7Encode() or to
  211.  * SEC_PKCS7EncoderStart() to create the encoded data, and finally to
  212.  * SEC_PKCS7DestroyContentInfo().
  213.  *
  214.  * An error results in a return value of NULL and an error set.
  215.  * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
  216.  */
  217. extern SEC_PKCS7ContentInfo *
  218. SEC_PKCS7CreateSignedData (CERTCertificate *cert,
  219.                SECCertUsage certusage,
  220.                CERTCertDBHandle *certdb,
  221.                SECOidTag digestalg,
  222.                SECItem *digest,
  223.                    SECKEYGetPasswordKey pwfn, void *pwfn_arg);
  224.  
  225. /*
  226.  * Create a PKCS7 certs-only container.
  227.  *
  228.  * "cert" is the (first) cert that will be included.
  229.  *
  230.  * "include_chain" specifies whether the entire chain for "cert" should
  231.  * be included.
  232.  *
  233.  * "certdb" is the cert database to use for finding the chain.
  234.  * It can be NULL in when "include_chain" is false, or when meaning
  235.  * use the default database.
  236.  *
  237.  * More certs and chains can be added via AddCertficate and AddCertChain.
  238.  *
  239.  * An error results in a return value of NULL and an error set.
  240.  * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
  241.  */
  242. extern SEC_PKCS7ContentInfo *
  243. SEC_PKCS7CreateCertsOnly (CERTCertificate *cert,
  244.               PRBool include_chain,
  245.               CERTCertDBHandle *certdb);
  246.  
  247. /*
  248.  * Start a PKCS7 enveloping context.
  249.  *
  250.  * "cert" is the cert for the recipient.  It will be checked for validity.
  251.  *
  252.  * "certusage" describes the encryption usage (e.g. certUsageEmailRecipient)
  253.  * XXX Maybe SECCertUsage should be split so that our caller just says
  254.  * "email" and *we* add the "recipient" part -- otherwise our caller
  255.  * could be lying about the usage; we do not want to allow encryption
  256.  * certs for signing or vice versa.
  257.  *
  258.  * "certdb" is the cert database to use for verifying the cert.
  259.  * It can be NULL if a default database is available (like in the client).
  260.  *
  261.  * "encalg" specifies the bulk encryption algorithm to use (e.g. SEC_OID_RC2).
  262.  *
  263.  * "keysize" specifies the bulk encryption key size, in bits.
  264.  *
  265.  * The return value can be passed to functions which add things to
  266.  * it like more recipients, then eventually to SEC_PKCS7Encode() or to
  267.  * SEC_PKCS7EncoderStart() to create the encoded data, and finally to
  268.  * SEC_PKCS7DestroyContentInfo().
  269.  *
  270.  * An error results in a return value of NULL and an error set.
  271.  * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
  272.  */
  273. extern SEC_PKCS7ContentInfo *
  274. SEC_PKCS7CreateEnvelopedData (CERTCertificate *cert,
  275.                   SECCertUsage certusage,
  276.                   CERTCertDBHandle *certdb,
  277.                   SECOidTag encalg,
  278.                   int keysize,
  279.                       SECKEYGetPasswordKey pwfn, void *pwfn_arg);
  280.  
  281. /*
  282.  * XXX There will be a similar routine for creating signedAndEnvelopedData.
  283.  * But its parameters will be different and I have no plans to implement
  284.  * it any time soon because we have no current need for it.
  285.  */
  286.  
  287. /*
  288.  * Create an empty PKCS7 data content info.
  289.  *
  290.  * An error results in a return value of NULL and an error set.
  291.  * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
  292.  */
  293. extern SEC_PKCS7ContentInfo *SEC_PKCS7CreateData (void);
  294.  
  295. /*
  296.  * Create an empty PKCS7 encrypted content info.
  297.  *
  298.  * "algorithm" specifies the bulk encryption algorithm to use.
  299.  * 
  300.  * An error results in a return value of NULL and an error set.
  301.  * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
  302.  */
  303. extern SEC_PKCS7ContentInfo *
  304. SEC_PKCS7CreateEncryptedData (SECOidTag algorithm, int keysize,
  305.                   SECKEYGetPasswordKey pwfn, void *pwfn_arg);
  306.  
  307. /*
  308.  * All of the following things return SECStatus to signal success or failure.
  309.  * Failure should have a more specific error status available via
  310.  * PORT_GetError()/XP_GetError().
  311.  */
  312.  
  313. /*
  314.  * Add the specified attribute to the authenticated (i.e. signed) attributes
  315.  * of "cinfo" -- "oidtag" describes the attribute and "value" is the
  316.  * value to be associated with it.  NOTE! "value" must already be encoded;
  317.  * no interpretation of "oidtag" is done.  Also, it is assumed that this
  318.  * signedData has only one signer -- if we ever need to add attributes
  319.  * when there is more than one signature, we need a way to specify *which*
  320.  * signature should get the attribute.
  321.  *
  322.  * XXX Technically, a signed attribute can have multiple values; if/when
  323.  * we ever need to support an attribute which takes multiple values, we
  324.  * either need to change this interface or create an AddSignedAttributeValue
  325.  * which can be called subsequently, and would then append a value.
  326.  *
  327.  * "cinfo" should be of type signedData (the only kind of pkcs7 data
  328.  * that is allowed authenticated attributes); SECFailure will be returned
  329.  * if it is not.
  330.  */
  331. extern SECStatus SEC_PKCS7AddSignedAttribute (SEC_PKCS7ContentInfo *cinfo,
  332.                           SECOidTag oidtag,
  333.                           SECItem *value);
  334.  
  335. /*
  336.  * Add "cert" and its entire chain to the set of certs included in "cinfo".
  337.  *
  338.  * "certdb" is the cert database to use for finding the chain.
  339.  * It can be NULL, meaning use the default database.
  340.  *
  341.  * "cinfo" should be of type signedData or signedAndEnvelopedData;
  342.  * SECFailure will be returned if it is not.
  343.  */
  344. extern SECStatus SEC_PKCS7AddCertChain (SEC_PKCS7ContentInfo *cinfo,
  345.                     CERTCertificate *cert,
  346.                     CERTCertDBHandle *certdb);
  347.  
  348. /*
  349.  * Add "cert" to the set of certs included in "cinfo".
  350.  *
  351.  * "cinfo" should be of type signedData or signedAndEnvelopedData;
  352.  * SECFailure will be returned if it is not.
  353.  */
  354. extern SECStatus SEC_PKCS7AddCertificate (SEC_PKCS7ContentInfo *cinfo,
  355.                       CERTCertificate *cert);
  356.  
  357. /*
  358.  * Add another recipient to an encrypted message.
  359.  *
  360.  * "cinfo" should be of type envelopedData or signedAndEnvelopedData;
  361.  * SECFailure will be returned if it is not.
  362.  *
  363.  * "cert" is the cert for the recipient.  It will be checked for validity.
  364.  *
  365.  * "certusage" describes the encryption usage (e.g. certUsageEmailRecipient)
  366.  * XXX Maybe SECCertUsage should be split so that our caller just says
  367.  * "email" and *we* add the "recipient" part -- otherwise our caller
  368.  * could be lying about the usage; we do not want to allow encryption
  369.  * certs for signing or vice versa.
  370.  *
  371.  * "certdb" is the cert database to use for verifying the cert.
  372.  * It can be NULL if a default database is available (like in the client).
  373.  */
  374. extern SECStatus SEC_PKCS7AddRecipient (SEC_PKCS7ContentInfo *cinfo,
  375.                     CERTCertificate *cert,
  376.                     SECCertUsage certusage,
  377.                     CERTCertDBHandle *certdb);
  378.  
  379. /*
  380.  * Add the signing time to the authenticated (i.e. signed) attributes
  381.  * of "cinfo".  This is expected to be included in outgoing signed
  382.  * messages for email (S/MIME) but is likely useful in other situations.
  383.  *
  384.  * This should only be added once; a second call will either do
  385.  * nothing or replace an old signing time with a newer one.
  386.  *
  387.  * XXX This will probably just shove the current time into "cinfo"
  388.  * but it will not actually get signed until the entire item is
  389.  * processed for encoding.  Is this (expected to be small) delay okay?
  390.  *
  391.  * "cinfo" should be of type signedData (the only kind of pkcs7 data
  392.  * that is allowed authenticated attributes); SECFailure will be returned
  393.  * if it is not.
  394.  */
  395. extern SECStatus SEC_PKCS7AddSigningTime (SEC_PKCS7ContentInfo *cinfo);
  396.  
  397. /*
  398.  * Add the signer's symmetric capabilities to the authenticated
  399.  * (i.e. signed) attributes of "cinfo".  This is expected to be
  400.  * included in outgoing signed messages for email (S/MIME).
  401.  *
  402.  * This can only be added once; a second call will return SECFailure.
  403.  *
  404.  * "cinfo" should be of type signedData or signedAndEnvelopedData;
  405.  * SECFailure will be returned if it is not.
  406.  */
  407. extern SECStatus SEC_PKCS7AddSymmetricCapabilities(SEC_PKCS7ContentInfo *cinfo);
  408.  
  409. /*
  410.  * Mark that the signer's certificate and its issuing chain should
  411.  * be included in the encoded data.  This is expected to be used
  412.  * in outgoing signed messages for email (S/MIME).
  413.  *
  414.  * "certdb" is the cert database to use for finding the chain.
  415.  * It can be NULL, meaning use the default database.
  416.  *
  417.  * "cinfo" should be of type signedData or signedAndEnvelopedData;
  418.  * SECFailure will be returned if it is not.
  419.  */
  420. extern SECStatus SEC_PKCS7IncludeCertChain (SEC_PKCS7ContentInfo *cinfo,
  421.                         CERTCertDBHandle *certdb);
  422.  
  423.  
  424. /*
  425.  * Set the content; it will be included and also hashed and/or encrypted
  426.  * as appropriate.  This is for in-memory content (expected to be "small")
  427.  * that will be included in the PKCS7 object.  All others should stream the
  428.  * content through when encoding (see SEC_PKCS7Encoder{Start,Update,Finish}).
  429.  *
  430.  * "buf" points to data of length "len"; it will be copied.
  431.  */
  432. extern SECStatus SEC_PKCS7SetContent (SEC_PKCS7ContentInfo *cinfo,
  433.                       const char *buf, unsigned long len);
  434.  
  435. /*
  436.  * Encode a PKCS7 object, in one shot.  All necessary components
  437.  * of the object must already be specified.  Either the data has
  438.  * already been included (via SetContent), or the data is detached,
  439.  * or there is no data at all (certs-only).
  440.  *
  441.  * "cinfo" specifies the object to be encoded.
  442.  *
  443.  * "outputfn" is where the encoded bytes will be passed.
  444.  *
  445.  * "outputarg" is an opaque argument to the above callback.
  446.  *
  447.  * "bulkkey" specifies the bulk encryption key to use.   This argument
  448.  * can be NULL if no encryption is being done, or if the bulk key should
  449.  * be generated internally (usually the case for EnvelopedData but never
  450.  * for EncryptedData, which *must* provide a bulk encryption key).
  451.  *
  452.  * "pwfn" is a callback for getting the password which protects the
  453.  * private key of the signer.  This argument can be NULL if it is known
  454.  * that no signing is going to be done.
  455.  *
  456.  * "pwfnarg" is an opaque argument to the above callback.
  457.  */
  458. extern SECStatus SEC_PKCS7Encode (SEC_PKCS7ContentInfo *cinfo,
  459.                   SEC_PKCS7EncoderOutputCallback outputfn,
  460.                   void *outputarg,
  461.                   PK11SymKey *bulkkey,
  462.                   SECKEYGetPasswordKey pwfn,
  463.                   void *pwfnarg);
  464.  
  465. /*
  466.  * Encode a PKCS7 object, in one shot.  All necessary components
  467.  * of the object must already be specified.  Either the data has
  468.  * already been included (via SetContent), or the data is detached,
  469.  * or there is no data at all (certs-only).  The output, rather than
  470.  * being passed to an output function as is done above, is all put
  471.  * into a SECItem.
  472.  *
  473.  * "pool" specifies a pool from which to allocate the result.
  474.  * It can be NULL, in which case memory is allocated generically.
  475.  *
  476.  * "dest" specifies a SECItem in which to put the result data.
  477.  * It can be NULL, in which case the entire item is allocated, too.
  478.  *
  479.  * "cinfo" specifies the object to be encoded.
  480.  *
  481.  * "bulkkey" specifies the bulk encryption key to use.   This argument
  482.  * can be NULL if no encryption is being done, or if the bulk key should
  483.  * be generated internally (usually the case for EnvelopedData but never
  484.  * for EncryptedData, which *must* provide a bulk encryption key).
  485.  *
  486.  * "pwfn" is a callback for getting the password which protects the
  487.  * private key of the signer.  This argument can be NULL if it is known
  488.  * that no signing is going to be done.
  489.  *
  490.  * "pwfnarg" is an opaque argument to the above callback.
  491.  */
  492. extern SECItem *SEC_PKCS7EncodeItem (PRArenaPool *pool,
  493.                      SECItem *dest,
  494.                      SEC_PKCS7ContentInfo *cinfo,
  495.                      PK11SymKey *bulkkey,
  496.                      SECKEYGetPasswordKey pwfn,
  497.                      void *pwfnarg);
  498.  
  499. /*
  500.  * For those who want to simply point to the pkcs7 contentInfo ASN.1
  501.  * template, and *not* call the encoding functions directly, the
  502.  * following function can be used -- after it is called, the entire
  503.  * PKCS7 contentInfo is ready to be encoded.
  504.  */
  505. extern SECStatus SEC_PKCS7PrepareForEncode (SEC_PKCS7ContentInfo *cinfo,
  506.                         PK11SymKey *bulkkey,
  507.                         SECKEYGetPasswordKey pwfn,
  508.                         void *pwfnarg);
  509.  
  510. /*
  511.  * Start the process of encoding a PKCS7 object.  The first part of
  512.  * the encoded object will be passed to the output function right away;
  513.  * after that it is expected that SEC_PKCS7EncoderUpdate will be called,
  514.  * streaming in the actual content that is getting included as well as
  515.  * signed or encrypted (or both).
  516.  *
  517.  * "cinfo" specifies the object to be encoded.
  518.  *
  519.  * "outputfn" is where the encoded bytes will be passed.
  520.  *
  521.  * "outputarg" is an opaque argument to the above callback.
  522.  *
  523.  * "bulkkey" specifies the bulk encryption key to use.   This argument
  524.  * can be NULL if no encryption is being done, or if the bulk key should
  525.  * be generated internally (usually the case for EnvelopedData but never
  526.  * for EncryptedData, which *must* provide a bulk encryption key).
  527.  *
  528.  * Returns an object to be passed to EncoderUpdate and EncoderFinish.
  529.  */
  530. extern SEC_PKCS7EncoderContext *
  531. SEC_PKCS7EncoderStart (SEC_PKCS7ContentInfo *cinfo,
  532.                SEC_PKCS7EncoderOutputCallback outputfn,
  533.                void *outputarg,
  534.                PK11SymKey *bulkkey);
  535.  
  536. /*
  537.  * Encode more contents, hashing and/or encrypting along the way.
  538.  */
  539. extern SECStatus SEC_PKCS7EncoderUpdate (SEC_PKCS7EncoderContext *p7ecx,
  540.                      const char *buf,
  541.                      unsigned long len);
  542.  
  543. /*
  544.  * No more contents; finish the signature creation, if appropriate,
  545.  * and then the encoding.
  546.  *
  547.  * "pwfn" is a callback for getting the password which protects the
  548.  * signer's private key.  This argument can be NULL if it is known
  549.  * that no signing is going to be done.
  550.  *
  551.  * "pwfnarg" is an opaque argument to the above callback.
  552.  */
  553. extern SECStatus SEC_PKCS7EncoderFinish (SEC_PKCS7EncoderContext *p7ecx,
  554.                      SECKEYGetPasswordKey pwfn,
  555.                      void *pwfnarg);
  556.  
  557. /*  Abort the underlying ASN.1 stream & set an error  */
  558. void SEC_PKCS7EncoderAbort(SEC_PKCS7EncoderContext *p7dcx, int error);
  559.  
  560. /* retrieve the algorithm ID used to encrypt the content info
  561.  * for encrypted and enveloped data.  The SECAlgorithmID pointer
  562.  * returned needs to be freed as it is a copy of the algorithm
  563.  * id in the content info.
  564.  */ 
  565. extern SECAlgorithmID *
  566. SEC_PKCS7GetEncryptionAlgorithm(SEC_PKCS7ContentInfo *cinfo); 
  567.  
  568. /* the content of an encrypted data content info is encrypted.
  569.  * it is assumed that for encrypted data, that the data has already
  570.  * been set and is in the "plainContent" field of the content info.
  571.  *
  572.  * cinfo is the content info to encrypt
  573.  *
  574.  * key is the key with which to perform the encryption.  if the
  575.  *     algorithm is a password based encryption algorithm, the
  576.  *     key is actually a password which will be processed per
  577.  *     PKCS #5.
  578.  * 
  579.  * in the event of an error, SECFailure is returned.  SECSuccess
  580.  * indicates a success.
  581.  */
  582. extern SECStatus 
  583. SEC_PKCS7EncryptContents(PRArenaPool *poolp,
  584.              SEC_PKCS7ContentInfo *cinfo, 
  585.              SECItem *key,
  586.              void *wincx); 
  587.     
  588. /* the content of an encrypted data content info is decrypted.
  589.  * it is assumed that for encrypted data, that the data has already
  590.  * been set and is in the "encContent" field of the content info.
  591.  *
  592.  * cinfo is the content info to decrypt
  593.  *
  594.  * key is the key with which to perform the decryption.  if the
  595.  *     algorithm is a password based encryption algorithm, the
  596.  *     key is actually a password which will be processed per
  597.  *     PKCS #5.
  598.  * 
  599.  * in the event of an error, SECFailure is returned.  SECSuccess
  600.  * indicates a success.
  601.  */
  602. extern SECStatus 
  603. SEC_PKCS7DecryptContents(PRArenaPool *poolp,
  604.              SEC_PKCS7ContentInfo *cinfo, 
  605.              SECItem *key,
  606.              void *wincx); 
  607.  
  608. /* retrieve the certificate list from the content info.  the list
  609.  * is a pointer to the list in the content info.  this should not
  610.  * be deleted or freed in any way short of calling 
  611.  * SEC_PKCS7DestroyContentInfo
  612.  */
  613. extern SECItem **
  614. SEC_PKCS7GetCertificateList(SEC_PKCS7ContentInfo *cinfo);
  615.  
  616. /* Returns the key length (in bits) of the algorithm used to encrypt
  617.    this object.  Returns 0 if it's not encrypted, or the key length is
  618.    irrelevant. */
  619. extern int 
  620. SEC_PKCS7GetKeyLength(SEC_PKCS7ContentInfo *cinfo);
  621.  
  622.  
  623. /************************************************************************/
  624. SEC_END_PROTOS
  625.  
  626. #endif /* _SECPKCS7_H_ */
  627.